<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
	<head>
		<title>Hierarchy Locations</title>
<link href="../docs-assets/Breadcrumbs.css" rel="stylesheet" rev="stylesheet" type="text/css">
		<meta name="viewport" content="width=device-width initial-scale=1">
		<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
		<meta http-equiv="Content-Language" content="en-gb">

<link href="../docs-assets/Contents.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Progress.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Navigation.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Fonts.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Base.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script>
function togglePopup(material_id) {
  var popup = document.getElementById(material_id);
  popup.classList.toggle("show");
}
</script>

<link href="../docs-assets/Popups.css" rel="stylesheet" rev="stylesheet" type="text/css">
<script src="http://code.jquery.com/jquery-1.12.4.min.js"
	integrity="sha256-ZosEbRLbNQzLpnKIkEdrPv7lOy9C27hHQ+Xp8a4MxAQ=" crossorigin="anonymous"></script>

<script src="../docs-assets/Bigfoot.js"></script>
<link href="../docs-assets/Bigfoot.css" rel="stylesheet" rev="stylesheet" type="text/css">
<link href="../docs-assets/Colours.css" rel="stylesheet" rev="stylesheet" type="text/css">
		
	</head>
	<body class="commentary-font">
		<nav role="navigation">
		<h1><a href="../index.html"><img src="../docs-assets/Inform.png" height=72> </a></h1>
<ul><li><a href="../index.html">home</a></li>
</ul><h2>Compiler</h2><ul>
<li><a href="../structure.html">structure</a></li>
<li><a href="../inbuildn.html">inbuild</a></li>
<li><a href="../inform7n.html">inform7</a></li>
<li><a href="../intern.html">inter</a></li>
<li><a href="../services.html">services</a></li>
<li><a href="../secrets.html">secrets</a></li>
</ul><h2>Other Tools</h2><ul>
<li><a href="../inblorbn.html">inblorb</a></li>
<li><a href="../inform6.html">inform6</a></li>
<li><a href="../inpolicyn.html">inpolicy</a></li>
</ul><h2>Resources</h2><ul>
<li><a href="../extensions.html">extensions</a></li>
<li><a href="../kits.html">kits</a></li>
</ul><h2>Repository</h2><ul>
<li><a href="https://github.com/ganelson/inform"><img src="../docs-assets/github.png" height=0> github</a></li>
</ul><h2>Related Projects</h2><ul>
<li><a href="https://github.com/ganelson/inweb"><img src="../docs-assets/github.png" height=0> inweb</a></li>
<li><a href="https://github.com/ganelson/intest"><img src="../docs-assets/github.png" height=0> intest</a></li>
</ul>
		</nav>
		<main role="main">
		<!-- Weave of 'Hierarchy Locations' generated by inweb -->
<div class="breadcrumbs">
    <ul class="crumbs"><li><a href="../index.html">Home</a></li><li><a href="../intern.html">Inter Modules</a></li><li><a href="index.html">building</a></li><li><a href="index.html#1">Chapter 1: Architecture</a></li><li><b>Hierarchy Locations</b></li></ul></div>
<p class="purpose">Location and naming rules for resources to be compiled in an Inter hierarchy.</p>

<ul class="toc"><li><a href="1-hl.html#SP1">&#167;1. Hierarchy locations</a></li><li><a href="1-hl.html#SP7">&#167;7. Finding HLs by ID or name</a></li><li><a href="1-hl.html#SP8">&#167;8. Finding HLs representing one-off global resources</a></li><li><a href="1-hl.html#SP9">&#167;9. Finding HLs representing resources in families of packages</a></li><li><a href="1-hl.html#SP16">&#167;16. Making one-off subpackages</a></li><li><a href="1-hl.html#SP17">&#167;17. Making packages systematically at attachment points</a></li><li><a href="1-hl.html#SP20">&#167;20. Bookkeeping</a></li><li><a href="1-hl.html#SP21">&#167;21. Finding inames by name</a></li></ul><hr class="tocbar">

<p class="commentary firstcommentary"><a id="SP1" class="paragraph-anchor"></a><b>&#167;1. Hierarchy locations.</b>A compiler such as <a href="../inform7/index.html" class="internal">inform7</a> needs to create many different resources &mdash;
arrays, functions and so on &mdash; and each one needs to be placed somewhere
in the hierarchy of an Inter tree, and given a name.
</p>

<p class="commentary">A <a href="1-hl.html#SP1" class="internal">hierarchy_location</a> is an abstract way to specify the rules for doing
that. The compiler creates a mass of these objects, and they are then indexed
by unique IDs, their <span class="extract"><span class="extract-syntax">access_number</span></span>s. The compiler can then, with essentially
no overhead, ask to create the resource with ID <span class="extract"><span class="extract-syntax">JINXED_WIZARDS_HL</span></span> (say),
and the machinery below will work out where it is to go, and what it is to
be called &mdash; <span class="extract"><span class="extract-syntax">/synoptic/pangrams/jinxed_wizards_fn</span></span>, say.
</p>

<p class="commentary">This leads to greater consistency, less duplication of book-keeping code,
and the ability to have a sort of registry of where everything will go:
see <a href="../runtime-module/2-hrr.html" class="internal">Hierarchy (in runtime)</a> for an example.
</p>

<p class="commentary">But it's also helpful when trying to use these resources. If the compiler needs
to make a function call to our hypothetical jinxed-wizards function, it can
simply use <span class="extract"><span class="extract-syntax">HierarchyLocations::iname(JINXED_WIZARDS_HL)</span></span> to obtain an <a href="1-in.html#SP3" class="internal">inter_name</a>
for where that function is (if it already exists) or will be (if not).
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">access_number</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">access_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">function_package_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">datum_package_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">location_requirement</span><span class="plain-syntax"> </span><span class="identifier-syntax">requirements</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">equates_to_iname</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">package_type</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">name_translation</span><span class="plain-syntax"> </span><span class="identifier-syntax">trans</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax">;</span>

<span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::new</span><button class="popup" onclick="togglePopup('usagePopup1')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup1">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::new</span></span>:<br/><a href="1-hl.html#SP2">&#167;2</a>, <a href="1-hl.html#SP4">&#167;4</a>, <a href="1-hl.html#SP5">&#167;5</a>, <a href="1-hl.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="reserved-syntax">location_requirement</span><span class="plain-syntax"> </span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_number</span><span class="plain-syntax"> = </span><span class="identifier-syntax">id</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">function_package_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">datum_package_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">equates_to_iname</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">package_type</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax"> = </span><a href="1-trn.html#SP2" class="function-link"><span class="function-syntax">Translation::same</span></a><span class="plain-syntax">();</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax"> = </span><span class="identifier-syntax">req</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">hl</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<ul class="endnotetexts"><li>The structure hierarchy_location is private to this section.</li></ul>
<p class="commentary firstcommentary"><a id="SP2" class="paragraph-anchor"></a><b>&#167;2. </b>We provide an API of five creator functions for HLs. First, for a resource
like a constant<sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup> (possibly translated in some way: see <a href="1-trn.html" class="internal">Translation</a>), and
which must be located at position <span class="extract"><span class="extract-syntax">req</span></span>.
</p>

<ul class="footnotetexts"><li class="footnote" id="fn:1"><p class="inwebfootnote"><sup id="fnref:1"><a href="#fn:1" rel="footnote">1</a></sup> Or a variable, or really anything self-contained under a single simple name
which is not a package of some kind.
<a href="#fnref:1" title="return to text"> &#x21A9;</a></p></li></ul>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::ctr</span><button class="popup" onclick="togglePopup('usagePopup2')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup2">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::ctr</span></span>:<br/><a href="1-hl.html#SP3">&#167;3</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">name_translation</span><span class="plain-syntax"> </span><span class="identifier-syntax">nt</span><span class="plain-syntax">, </span><span class="reserved-syntax">location_requirement</span><span class="plain-syntax"> </span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP1" class="function-link"><span class="function-syntax">HierarchyLocations::new</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">req</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax"> = </span><span class="identifier-syntax">nt</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><a href="1-hl.html#SP7" class="function-link"><span class="function-syntax">HierarchyLocations::index</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">hl</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP3" class="paragraph-anchor"></a><b>&#167;3. </b>Second, the same thing but with no translation needed:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::con</span><button class="popup" onclick="togglePopup('usagePopup3')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup3">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::con</span></span>:<br/><a href="1-hl.html#SP21">&#167;21</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">location_requirement</span><span class="plain-syntax"> </span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-hl.html#SP2" class="function-link"><span class="function-syntax">HierarchyLocations::ctr</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><a href="1-trn.html#SP2" class="function-link"><span class="function-syntax">Translation::same</span></a><span class="plain-syntax">(), </span><span class="identifier-syntax">req</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP4" class="paragraph-anchor"></a><b>&#167;4. </b>Third, for a function, possibly translated in some way, again at <span class="extract"><span class="extract-syntax">req</span></span>:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::fun</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">name_translation</span><span class="plain-syntax"> </span><span class="identifier-syntax">nt</span><span class="plain-syntax">, </span><span class="reserved-syntax">location_requirement</span><span class="plain-syntax"> </span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP1" class="function-link"><span class="function-syntax">HierarchyLocations::new</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">req</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">nt</span><span class="plain-syntax">.</span><span class="element-syntax">translate_to</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">function_package_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax"> = </span><span class="identifier-syntax">nt</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><a href="1-hl.html#SP7" class="function-link"><span class="function-syntax">HierarchyLocations::index</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">hl</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP5" class="paragraph-anchor"></a><b>&#167;5. </b>Fourth, for a package of a given type, which must live at <span class="extract"><span class="extract-syntax">req</span></span>:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::pkg</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ptype_name</span><span class="plain-syntax">, </span><span class="reserved-syntax">location_requirement</span><span class="plain-syntax"> </span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP1" class="function-link"><span class="function-syntax">HierarchyLocations::new</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">req</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">package_type</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">ptype_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><a href="1-hl.html#SP7" class="function-link"><span class="function-syntax">HierarchyLocations::index</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">hl</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP6" class="paragraph-anchor"></a><b>&#167;6. </b>Finally, for a datum package:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::dat</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">name_translation</span><span class="plain-syntax"> </span><span class="identifier-syntax">nt</span><span class="plain-syntax">, </span><span class="reserved-syntax">location_requirement</span><span class="plain-syntax"> </span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP1" class="function-link"><span class="function-syntax">HierarchyLocations::new</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">req</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">nt</span><span class="plain-syntax">.</span><span class="element-syntax">translate_to</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">datum_package_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax"> = </span><span class="identifier-syntax">nt</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><a href="1-hl.html#SP7" class="function-link"><span class="function-syntax">HierarchyLocations::index</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">hl</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP7" class="paragraph-anchor"></a><b>&#167;7. Finding HLs by ID or name.</b>As noted above, HLs are identified with ID numbers for speed, and this means
that an array must be maintained so that the <a href="1-hl.html#SP1" class="internal">hierarchy_location</a> for a
given ID can be found quickly. We also sometimes want to look them up by name,
which is slower, but the hashing used by a <span class="extract"><span class="extract-syntax">dictionary</span></span> makes even that tolerable.
</p>

<p class="commentary">Both of these forms of lookup need an index to be kept, so HLs must be registered
for use with any tree which will need them, using the following.
</p>

<p class="commentary">Note that HLs for plugs all have the ID -1, so those are indexed only by name.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HierarchyLocations::index</span><button class="popup" onclick="togglePopup('usagePopup4')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup4">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::index</span></span>:<br/><a href="1-hl.html#SP2">&#167;2</a>, <a href="1-hl.html#SP4">&#167;4</a>, <a href="1-hl.html#SP5">&#167;5</a>, <a href="1-hl.html#SP6">&#167;6</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax"> = </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_number</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">id</span><span class="plain-syntax"> &gt;= </span><span class="constant-syntax">0</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">id</span><span class="plain-syntax"> &lt; </span><span class="identifier-syntax">NO_DEFINED_HL_VALUES</span><span class="plain-syntax">))</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">.</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HLs_indexed_by_id</span><span class="plain-syntax">[</span><span class="identifier-syntax">id</span><span class="plain-syntax">] = </span><span class="identifier-syntax">hl</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_package_of_this_type</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">Dictionaries::create</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">.</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HLs_indexed_by_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">Dictionaries::write_value</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">.</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HLs_indexed_by_name</span><span class="plain-syntax">,</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">, (</span><span class="reserved-syntax">void</span><span class="plain-syntax"> *) </span><span class="identifier-syntax">hl</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::id_to_HL</span><button class="popup" onclick="togglePopup('usagePopup5')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup5">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::id_to_HL</span></span>:<br/><a href="1-hl.html#SP8">&#167;8</a>, <a href="1-hl.html#SP14">&#167;14</a>, <a href="1-hl.html#SP15">&#167;15</a>, <a href="1-hl.html#SP16">&#167;16</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">id</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">id</span><span class="plain-syntax"> &gt;= </span><span class="identifier-syntax">NO_DEFINED_HL_VALUES</span><span class="plain-syntax">)) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"HL ID out of range"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">.</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HLs_indexed_by_id</span><span class="plain-syntax">[</span><span class="identifier-syntax">id</span><span class="plain-syntax">] == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"undeclared HL ID"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">.</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HLs_indexed_by_id</span><span class="plain-syntax">[</span><span class="identifier-syntax">id</span><span class="plain-syntax">];</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::name_to_HL</span><button class="popup" onclick="togglePopup('usagePopup6')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup6">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::name_to_HL</span></span>:<br/><a href="1-hl.html#SP8">&#167;8</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"empty HL name"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Dictionaries::find</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">.</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HLs_indexed_by_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">) == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> (</span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *)</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">Dictionaries::read_value</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">.</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HLs_indexed_by_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP8" class="paragraph-anchor"></a><b>&#167;8. Finding HLs representing one-off global resources.</b>The two functions here allow the client to get an iname for a resource which
occurs just once in the whole repository.
</p>

<p class="commentary">For example, <span class="extract"><span class="extract-syntax">HierarchyLocations::iname(I, UN_BUILDING_HL)</span></span> might return the
iname <span class="extract"><span class="extract-syntax">/main/generic/UN_building</span></span>. The package location, here <span class="extract"><span class="extract-syntax">/main/generic</span></span>,
and the name, here <span class="extract"><span class="extract-syntax">UN_building</span></span>, would both be specified explicitly in the HL.
So this is the simplest case.
</p>

<p class="commentary">In response to these requests, we actually never return the <a href="1-hl.html#SP1" class="internal">hierarchy_location</a>
itself; our users don't care about that. We return the <a href="1-in.html#SP3" class="internal">inter_name</a> for the
resource in question.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::iname</span><button class="popup" onclick="togglePopup('usagePopup7')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup7">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::iname</span></span>:<br/><a href="1-hl.html#SP15_1">&#167;15.1</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP7" class="function-link"><span class="function-syntax">HierarchyLocations::id_to_HL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP8_1" class="named-paragraph-link"><span class="named-paragraph">Work out the iname for this HL</span><span class="named-paragraph-number">8.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::name_to_iname</span><button class="popup" onclick="togglePopup('usagePopup8')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup8">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::name_to_iname</span></span>:<br/><a href="1-hl.html#SP21">&#167;21</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP7" class="function-link"><span class="function-syntax">HierarchyLocations::name_to_HL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP8_1" class="named-paragraph-link"><span class="named-paragraph">Work out the iname for this HL</span><span class="named-paragraph-number">8.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP8_1" class="paragraph-anchor"></a><b>&#167;8.1. </b>The result of the following is cached in <span class="extract"><span class="extract-syntax">hl-&gt;equates_to_iname</span></span>, so that
it only needs to be worked out once.
</p>

<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Work out the iname for this HL</span><span class="named-paragraph-number">8.1</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_package_of_this_type</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"this must be found with HierarchyLocations::iip"</span><span class="plain-syntax">);</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">equates_to_iname</span><span class="plain-syntax">) </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">equates_to_iname</span><span class="plain-syntax">;</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">must_be_plug</span><span class="plain-syntax">) </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP8_1_1" class="named-paragraph-link"><span class="named-paragraph">Then make it a plug</span><span class="named-paragraph-number">8.1.1</span></a></span><span class="plain-syntax">;</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">pack</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP8_1_2" class="named-paragraph-link"><span class="named-paragraph">Work out and request the package to make this in</span><span class="named-paragraph-number">8.1.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP8_1_3" class="named-paragraph-link"><span class="named-paragraph">Make the iname inside this package</span><span class="named-paragraph-number">8.1.3</span></a></span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-hl.html#SP8">&#167;8</a> (twice).</li></ul>
<p class="commentary firstcommentary"><a id="SP8_1_1" class="paragraph-anchor"></a><b>&#167;8.1.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Then make it a plug</span><span class="named-paragraph-number">8.1.1</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">equates_to_iname</span><span class="plain-syntax"> = </span><a href="1-in.html#SP6" class="function-link"><span class="function-syntax">InterNames::explicitly_named_plug</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">equates_to_iname</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-hl.html#SP8_1">&#167;8.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP8_1_2" class="paragraph-anchor"></a><b>&#167;8.1.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Work out and request the package to make this in</span><span class="named-paragraph-number">8.1.2</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="identifier-syntax">pack</span><span class="plain-syntax"> = </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">this_exact_package</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">this_exact_package_not_yet_created</span><span class="plain-syntax"> &gt;= </span><span class="constant-syntax">0</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP8_1_2_1" class="named-paragraph-link"><span class="named-paragraph">Choose an exotic package instead</span><span class="named-paragraph-number">8.1.2.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">pack</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"package can't be found"</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-hl.html#SP8_1">&#167;8.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP8_1_2_1" class="paragraph-anchor"></a><b>&#167;8.1.2.1. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Choose an exotic package instead</span><span class="named-paragraph-number">8.1.2.1</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">CORE_MODULE</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">pack</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Hierarchy::exotic_package</span><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">this_exact_package_not_yet_created</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">pack</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"unable to determine package and therefore iname"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">ifndef</span><span class="plain-syntax"> </span><span class="identifier-syntax">CORE_MODULE</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"exotic packages are not available in inter"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">endif</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-hl.html#SP8_1_2">&#167;8.1.2</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP8_1_3" class="paragraph-anchor"></a><b>&#167;8.1.3. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Make the iname inside this package</span><span class="named-paragraph-number">8.1.3</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">function_package_name</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">equates_to_iname</span><span class="plain-syntax"> = </span><a href="1-pck.html#SP14" class="function-link"><span class="function-syntax">Packaging::function</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">,</span>
<span class="plain-syntax">            </span><a href="1-in.html#SP6" class="function-link"><span class="function-syntax">InterNames::explicitly_named</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">function_package_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">),</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">datum_package_name</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">equates_to_iname</span><span class="plain-syntax"> = </span><a href="1-pck.html#SP15" class="function-link"><span class="function-syntax">Packaging::datum_text</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">,</span>
<span class="plain-syntax">            </span><a href="1-in.html#SP6" class="function-link"><span class="function-syntax">InterNames::explicitly_named</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">datum_package_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">),</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">equates_to_iname</span><span class="plain-syntax"> = </span><a href="1-in.html#SP6" class="function-link"><span class="function-syntax">InterNames::explicitly_named</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">pack</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    }</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">translate_to</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><a href="1-in.html#SP11" class="function-link"><span class="function-syntax">InterNames::set_translation</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">equates_to_iname</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">translate_to</span><span class="plain-syntax">);</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">equates_to_iname</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-hl.html#SP8_1">&#167;8.1</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP9" class="paragraph-anchor"></a><b>&#167;9. Finding HLs representing resources in families of packages.</b>Suppose we want to have packages representing, say, South American countries, and
the compiler wants to create a constant <span class="extract"><span class="extract-syntax">capital_city</span></span> in each of these packages.
</p>

<p class="commentary">There will be a single HL supplying the rules to do this, but multiple inames
will be produced as the compiler makes multiple calls:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    ... </span><span class="function-syntax">HierarchyLocations::make_iname_in</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">CAPITAL_CITY_HL</span><span class="plain-syntax">, </span><span class="identifier-syntax">uruguay_package</span><span class="plain-syntax">) ...</span>
<span class="plain-syntax">    ... </span><span class="function-syntax">HierarchyLocations::make_iname_in</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">CAPITAL_CITY_HL</span><span class="plain-syntax">, </span><span class="identifier-syntax">peru_package</span><span class="plain-syntax">) ...</span>
<span class="plain-syntax">    ... </span><span class="function-syntax">HierarchyLocations::make_iname_in</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">CAPITAL_CITY_HL</span><span class="plain-syntax">, </span><span class="identifier-syntax">chile_package</span><span class="plain-syntax">) ...</span>
</pre>
<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::make_iname_in</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-hl.html#SP15" class="function-link"><span class="function-syntax">HierarchyLocations::iip</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">EMPTY_WORDING</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="constant-syntax">DEFAULT_INAME_TRUNCATION</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP10" class="paragraph-anchor"></a><b>&#167;10. </b>That might, say, produce constants with the Inter symbols like so:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    /</span><span class="identifier-syntax">main</span><span class="plain-syntax">/</span><span class="identifier-syntax">south_america</span><span class="plain-syntax">/</span><span class="identifier-syntax">uruguay</span><span class="plain-syntax">/</span><span class="identifier-syntax">capital_city</span>
<span class="plain-syntax">    /</span><span class="identifier-syntax">main</span><span class="plain-syntax">/</span><span class="identifier-syntax">south_america</span><span class="plain-syntax">/</span><span class="identifier-syntax">peru</span><span class="plain-syntax">/</span><span class="identifier-syntax">capital_city</span>
<span class="plain-syntax">    /</span><span class="identifier-syntax">main</span><span class="plain-syntax">/</span><span class="identifier-syntax">south_america</span><span class="plain-syntax">/</span><span class="identifier-syntax">chile</span><span class="plain-syntax">/</span><span class="identifier-syntax">capital_city</span>
</pre>
<p class="commentary">When final code is generated from these, the constants will probably end up
with bland identifiers like <span class="extract"><span class="extract-syntax">capital_city_U1</span></span>, <span class="extract"><span class="extract-syntax">capital_city_U2</span></span>, and so on.
If we don't want that, we can make an exception like so:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    ... </span><span class="function-syntax">HierarchyLocations::make_iname_in</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">CAPITAL_CITY_HL</span><span class="plain-syntax">, </span><span class="identifier-syntax">uruguay_package</span><span class="plain-syntax">) ...</span>
<span class="plain-syntax">    ... </span><span class="function-syntax">HierarchyLocations::make_iname_with_specific_translation</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">CAPITAL_CITY_HL</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">I</span><span class="string-syntax">"Lima"</span><span class="plain-syntax">, </span><span class="identifier-syntax">peru_package</span><span class="plain-syntax">) ...</span>
<span class="plain-syntax">    ... </span><span class="function-syntax">HierarchyLocations::make_iname_in</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">CAPITAL_CITY_HL</span><span class="plain-syntax">, </span><span class="identifier-syntax">chile_package</span><span class="plain-syntax">) ...</span>
</pre>
<p class="commentary">Our three capitals would then translate to <span class="extract"><span class="extract-syntax">capital_city_U1</span></span>, <span class="extract"><span class="extract-syntax">Lima</span></span>, and
<span class="extract"><span class="extract-syntax">capital_city_U2</span></span>.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::make_iname_with_specific_translation</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">translation</span><span class="plain-syntax">, </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-hl.html#SP15" class="function-link"><span class="function-syntax">HierarchyLocations::iip</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">EMPTY_WORDING</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">translation</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="constant-syntax">DEFAULT_INAME_TRUNCATION</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP11" class="paragraph-anchor"></a><b>&#167;11. </b>Sometimes we want the name itself to be more meaningful, or at least, more
legible when Inter code is printed out. We can do that by attaching a "memo"
of wording to its name. For example, if <span class="extract"><span class="extract-syntax">W</span></span> is the wording "Uruguay", then
calling:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="function-syntax">HierarchyLocations::make_iname_with_memo</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">COUNTRY_HL</span><span class="plain-syntax">, </span><span class="identifier-syntax">uruguay_package</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">)</span>
</pre>
<p class="commentary">might produce the iname <span class="extract"><span class="extract-syntax">/main/south_america/uruguay/C3_uruguay</span></span>; a subsequent
call in a different package, with a different wording, might then produce
<span class="extract"><span class="extract-syntax">/main/south_america/uruguay/C4_trinidad_and_tobago</span></span>, and so on. (The choice of
<span class="extract"><span class="extract-syntax">C</span></span> as the prefix would be made in the HL, which specifies naming conventions.)
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::make_iname_with_memo</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-hl.html#SP15" class="function-link"><span class="function-syntax">HierarchyLocations::iip</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="constant-syntax">DEFAULT_INAME_TRUNCATION</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::make_iname_with_shorter_memo</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-hl.html#SP15" class="function-link"><span class="function-syntax">HierarchyLocations::iip</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="constant-syntax">DEFAULT_INAME_TRUNCATION</span><span class="plain-syntax"> - </span><span class="constant-syntax">5</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP12" class="paragraph-anchor"></a><b>&#167;12. </b>Note that the HL, in this example <span class="extract"><span class="extract-syntax">COUNTRY_HL</span></span>, keeps track of how many of
these inames it has made, so that it can increment the index number &mdash; in those
two cases, 3 and then 4. If we need to override this with a specific number <span class="extract"><span class="extract-syntax">x</span></span>
for some reason, we can use this variant:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::make_iname_with_memo_and_value</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">x</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-hl.html#SP15" class="function-link"><span class="function-syntax">HierarchyLocations::iip</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">x</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="constant-syntax">DEFAULT_INAME_TRUNCATION</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::make_iname_with_shorter_memo_and_value</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">x</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-hl.html#SP15" class="function-link"><span class="function-syntax">HierarchyLocations::iip</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">x</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="constant-syntax">DEFAULT_INAME_TRUNCATION</span><span class="plain-syntax"> - </span><span class="constant-syntax">10</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP13" class="paragraph-anchor"></a><b>&#167;13. </b>Finally, it's often useful to "derive" a name: to say that a resource in a
given package <span class="extract"><span class="extract-syntax">P</span></span> should have a name based on the name of an existing iname.
For example, the HL <span class="extract"><span class="extract-syntax">POPULATION_HL</span></span> might have the rule that names are made
by suffixing <span class="extract"><span class="extract-syntax">_POP</span></span> to an existing iname. Calling <a href="1-hl.html#SP13" class="internal">HierarchyLocations::derive_iname_in</a>
might then produce a name like <span class="extract"><span class="extract-syntax">C3_uruguay_POP</span></span>, derived from the existing iname
<span class="extract"><span class="extract-syntax">C3_uruguay</span></span>.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::derive_iname_in</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">from</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-hl.html#SP15" class="function-link"><span class="function-syntax">HierarchyLocations::iip</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">EMPTY_WORDING</span><span class="plain-syntax">, </span><span class="identifier-syntax">from</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="constant-syntax">DEFAULT_INAME_TRUNCATION</span><span class="plain-syntax">);</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP14" class="paragraph-anchor"></a><b>&#167;14. </b>And this variant form ensures that any translation already made to <span class="extract"><span class="extract-syntax">from</span></span>
is transferred to a similarly derived translation name for the result.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::derive_iname_in_translating</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">from</span><span class="plain-syntax">, </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">iname</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP15" class="function-link"><span class="function-syntax">HierarchyLocations::iip</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">EMPTY_WORDING</span><span class="plain-syntax">, </span><span class="identifier-syntax">from</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><span class="constant-syntax">DEFAULT_INAME_TRUNCATION</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">)</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><span class="string-syntax">"%n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">from</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::ne</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">, </span><a href="1-in.html#SP11" class="function-link"><span class="function-syntax">InterNames::get_translation</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">from</span><span class="plain-syntax">))) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP7" class="function-link"><span class="function-syntax">HierarchyLocations::id_to_HL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">name_generator</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">from</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">)</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"%S"</span><span class="plain-syntax">, </span><a href="1-in.html#SP11" class="function-link"><span class="function-syntax">InterNames::get_translation</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">from</span><span class="plain-syntax">));</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">TT</span><span class="plain-syntax">)</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">Str::truncate</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                </span><span class="constant-syntax">30</span><span class="plain-syntax">  - </span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">name_generator</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">derived_prefix</span><span class="plain-syntax">)</span>
<span class="plain-syntax">                    - </span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">name_generator</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">derived_suffix</span><span class="plain-syntax">));</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">TT</span><span class="plain-syntax">, </span><span class="string-syntax">"%S%S%S"</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">name_generator</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">derived_prefix</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">T</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">name_generator</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">derived_suffix</span><span class="plain-syntax">);</span>
<span class="plain-syntax">            </span><a href="1-in.html#SP11" class="function-link"><span class="function-syntax">InterNames::set_translation</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">iname</span><span class="plain-syntax">, </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">TT</span><span class="plain-syntax">));</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">)</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">TT</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        }</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">F</span><span class="plain-syntax">)</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">iname</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP15" class="paragraph-anchor"></a><b>&#167;15. </b>All of the above use this command back-end:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::iip</span><button class="popup" onclick="togglePopup('usagePopup9')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup9">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::iip</span></span>:<br/><a href="1-hl.html#SP8_1">&#167;8.1</a>, <a href="1-hl.html#SP9">&#167;9</a>, <a href="1-hl.html#SP10">&#167;10</a>, <a href="1-hl.html#SP11">&#167;11</a>, <a href="1-hl.html#SP12">&#167;12</a>, <a href="1-hl.html#SP13">&#167;13</a>, <a href="1-hl.html#SP14">&#167;14</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">wording</span><span class="plain-syntax"> </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">derive_from</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">fix</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">imposed_name</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">truncation</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP7" class="function-link"><span class="function-syntax">HierarchyLocations::id_to_HL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">);</span>

<span class="plain-syntax">    </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP15_1" class="named-paragraph-link"><span class="named-paragraph">Verify that the proposed package P meets requirements</span><span class="named-paragraph-number">15.1</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">iname</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">translate_to</span><span class="plain-syntax">)  {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">T</span><span class="plain-syntax"> = </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">translate_to</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP15_2" class="named-paragraph-link"><span class="named-paragraph">Make the actual iname</span><span class="named-paragraph-number">15.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">by_imposition</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">T</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP15_2" class="named-paragraph-link"><span class="named-paragraph">Make the actual iname</span><span class="named-paragraph-number">15.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">name_generator</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">temp_iname</span><span class="plain-syntax"> =</span>
<span class="plain-syntax">            (</span><span class="identifier-syntax">derive_from</span><span class="plain-syntax">) ? </span><a href="1-in.html#SP7" class="function-link"><span class="function-syntax">InterNames::derived</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">name_generator</span><span class="plain-syntax">, </span><span class="identifier-syntax">derive_from</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">)</span>
<span class="plain-syntax">                          : </span><a href="1-in.html#SP7" class="function-link"><span class="function-syntax">InterNames::generated</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">name_generator</span><span class="plain-syntax">, </span><span class="identifier-syntax">fix</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">W</span><span class="plain-syntax"> = </span><span class="identifier-syntax">EMPTY_WORDING</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="string-syntax">"%n"</span><span class="plain-syntax">, </span><span class="identifier-syntax">temp_iname</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">Str::truncate</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="identifier-syntax">truncation</span><span class="plain-syntax"> + </span><span class="constant-syntax">5</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP15_2" class="named-paragraph-link"><span class="named-paragraph">Make the actual iname</span><span class="named-paragraph-number">15.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">)</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">T</span><span class="plain-syntax"> = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">        </span><span class="named-paragraph-container code-font"><a href="1-hl.html#SP15_2" class="named-paragraph-link"><span class="named-paragraph">Make the actual iname</span><span class="named-paragraph-number">15.2</span></a></span><span class="plain-syntax">;</span>
<span class="plain-syntax">    }</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">then_make_unique</span><span class="plain-syntax">) </span><a href="1-in.html#SP11" class="function-link"><span class="function-syntax">InterNames::set_flag</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">iname</span><span class="plain-syntax">, </span><span class="identifier-syntax">MAKE_NAME_UNIQUE_ISYMF</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">iname</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP15_1" class="paragraph-anchor"></a><b>&#167;15.1. </b>We do nothing to change matters here. But an HL can specify that it may only
be used to generate inames in, say, a package of type <span class="extract"><span class="extract-syntax">_country</span></span>: and an
internal error is thrown if this is violated. So compliance is not automatic,
but it is at least policed.
</p>

<p class="commentary"><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Verify that the proposed package P meets requirements</span><span class="named-paragraph-number">15.1</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_package_of_this_type</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) &amp;&amp;</span>
<span class="plain-syntax">        (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_enclosure</span><span class="plain-syntax"> == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">))</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"this must be found with HierarchyLocations::iname"</span><span class="plain-syntax">);</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_enclosure</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="1-ls.html#SP19" class="function-link"><span class="function-syntax">LargeScale::package_type_enclosing</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">eventual_type</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"subpackage not in enclosing superpackage"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">P</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"iname in null package"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">eventual_type</span><span class="plain-syntax"> !=</span>
<span class="plain-syntax">        </span><a href="1-ls.html#SP19" class="function-link"><span class="function-syntax">LargeScale::package_type</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_package_of_this_type</span><span class="plain-syntax">)) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"Access name: %S, function: %S\n"</span><span class="plain-syntax">,</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">function_package_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">LOG</span><span class="plain-syntax">(</span><span class="string-syntax">"Have type: $3, required: %S\n"</span><span class="plain-syntax">,</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">eventual_type</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_package_of_this_type</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"iname in superpackage of the wrong type"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    }</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-hl.html#SP15">&#167;15</a>.</li></ul>
<p class="commentary firstcommentary"><a id="SP15_2" class="paragraph-anchor"></a><b>&#167;15.2. </b><span class="named-paragraph-container code-font"><span class="named-paragraph-defn">Make the actual iname</span><span class="named-paragraph-number">15.2</span></span><span class="comment-syntax"> =</span>
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">function_package_name</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">iname</span><span class="plain-syntax"> = </span><a href="1-pck.html#SP14" class="function-link"><span class="function-syntax">Packaging::function</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">,</span>
<span class="plain-syntax">            </span><a href="1-in.html#SP6" class="function-link"><span class="function-syntax">InterNames::explicitly_named</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">function_package_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">), </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">trans</span><span class="plain-syntax">.</span><span class="element-syntax">by_imposition</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">iname</span><span class="plain-syntax"> = </span><a href="1-in.html#SP6" class="function-link"><span class="function-syntax">InterNames::explicitly_named_with_memo</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">imposed_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">truncation</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">iname</span><span class="plain-syntax"> = </span><a href="1-in.html#SP6" class="function-link"><span class="function-syntax">InterNames::explicitly_named_with_memo</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">truncation</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">iname</span><span class="plain-syntax"> = </span><a href="1-in.html#SP6" class="function-link"><span class="function-syntax">InterNames::explicitly_named_with_memo</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">, </span><span class="identifier-syntax">W</span><span class="plain-syntax">, </span><span class="identifier-syntax">truncation</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">T</span><span class="plain-syntax">) &gt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) &amp;&amp; (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">)) </span><a href="1-in.html#SP11" class="function-link"><span class="function-syntax">InterNames::set_translation</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">iname</span><span class="plain-syntax">, </span><span class="identifier-syntax">T</span><span class="plain-syntax">);</span>
</pre>
<ul class="endnotetexts"><li>This code is used in <a href="1-hl.html#SP15">&#167;15</a> (four times).</li></ul>
<p class="commentary firstcommentary"><a id="SP16" class="paragraph-anchor"></a><b>&#167;16. Making one-off subpackages.</b>This is used very little. (In <a href="../inform7/index.html" class="internal">inform7</a>, currently only for making the packages
holding built-in activity or action rulebooks.)
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::subpackage</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">, </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">P</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hl</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP7" class="function-link"><span class="function-syntax">HierarchyLocations::id_to_HL</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">id</span><span class="plain-syntax">);</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">P</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"no superpackage"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">package_type</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"HL does not specify a type"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_package_of_this_type</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">eventual_type</span><span class="plain-syntax"> !=</span>
<span class="plain-syntax">            </span><a href="1-ls.html#SP19" class="function-link"><span class="function-syntax">LargeScale::package_type</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_package_of_this_type</span><span class="plain-syntax">))</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"subpackage in superpackage of wrong type"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_enclosure</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><a href="1-ls.html#SP19" class="function-link"><span class="function-syntax">LargeScale::package_type_enclosing</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">P</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">eventual_type</span><span class="plain-syntax">) == </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">)</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"subpackage not in enclosing superpackage"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"HL does not call for a package"</span><span class="plain-syntax">);</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-pck.html#SP2" class="function-link"><span class="function-syntax">Packaging::request</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><a href="1-in.html#SP6" class="function-link"><span class="function-syntax">InterNames::explicitly_named</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">access_name</span><span class="plain-syntax">, </span><span class="identifier-syntax">P</span><span class="plain-syntax">),</span>
<span class="plain-syntax">        </span><a href="1-ls.html#SP19" class="function-link"><span class="function-syntax">LargeScale::package_type</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">hl</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">package_type</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP17" class="paragraph-anchor"></a><b>&#167;17. Making packages systematically at attachment points.</b>This is used a great deal. Instead of making a single iname, or a single package,
we want to make a family of packages, sequentially numbered in some way, at a
given position in the hierarchy. Such families are created at "hierarchy
attachment points", and the process of adding another package to the family
is called "attachment".
</p>

<p class="commentary">Like HLs, HAPs are identified by number, but this is a different and independent
numbering system.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">hierarchy_attachment_point</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">hap_id</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name_stem</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">type</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">location_requirement</span><span class="plain-syntax"> </span><span class="identifier-syntax">requirements</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">CLASS_DEFINITION</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">hierarchy_attachment_point</span><span class="plain-syntax">;</span>
</pre>
<ul class="endnotetexts"><li>The structure hierarchy_attachment_point is accessed in 1/pck, 1/in and here.</li></ul>
<p class="commentary firstcommentary"><a id="SP18" class="paragraph-anchor"></a><b>&#167;18. </b>Once again, these are indexed for speedy retrieval by ID number:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">hierarchy_attachment_point</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::att</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">stem</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">ptype_name</span><span class="plain-syntax">, </span><span class="reserved-syntax">location_requirement</span><span class="plain-syntax"> </span><span class="identifier-syntax">req</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">id</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">id</span><span class="plain-syntax"> &gt;= </span><span class="identifier-syntax">NO_DEFINED_HAP_VALUES</span><span class="plain-syntax">)) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"HAP ID out of range"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_attachment_point</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hap</span><span class="plain-syntax"> = </span><span class="identifier-syntax">CREATE</span><span class="plain-syntax">(</span><span class="reserved-syntax">hierarchy_attachment_point</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">hap_id</span><span class="plain-syntax"> = </span><span class="identifier-syntax">id</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax"> = </span><span class="identifier-syntax">req</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">name_stem</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">stem</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">type</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Str::duplicate</span><span class="plain-syntax">(</span><span class="identifier-syntax">ptype_name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">.</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HAPs_indexed_by_id</span><span class="plain-syntax">[</span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">hap_id</span><span class="plain-syntax">] = </span><span class="identifier-syntax">hap</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">hap</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">hierarchy_attachment_point</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::id_to_HAP</span><button class="popup" onclick="togglePopup('usagePopup10')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup10">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::id_to_HAP</span></span>:<br/><a href="1-hl.html#SP19">&#167;19</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">id</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">id</span><span class="plain-syntax"> &lt; </span><span class="constant-syntax">0</span><span class="plain-syntax">) || (</span><span class="identifier-syntax">id</span><span class="plain-syntax"> &gt;= </span><span class="identifier-syntax">NO_DEFINED_HAP_VALUES</span><span class="plain-syntax">)) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"HAP ID out of range"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">.</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HAPs_indexed_by_id</span><span class="plain-syntax">[</span><span class="identifier-syntax">id</span><span class="plain-syntax">] == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"undeclared HAP ID"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">.</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HAPs_indexed_by_id</span><span class="plain-syntax">[</span><span class="identifier-syntax">id</span><span class="plain-syntax">];</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP19" class="paragraph-anchor"></a><b>&#167;19. </b>The API is now very simple. <span class="extract"><span class="extract-syntax">HierarchyLocations::attach_new_package(I, M, R, id)</span></span>
attaches another package. R and M need only be specified if the location requirements
of the HAL do not imply a definite position already; M is meaningful only if the
requirements are to put everything in a submodule of a given module, and then M
is that module. For example:
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="plain-syntax">    </span><span class="identifier-syntax">vf_req</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Hierarchy::package_within</span><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">, </span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="identifier-syntax">VERB_FORMS_HAP</span><span class="plain-syntax">);</span>
</pre>
<p class="commentary">attaches a new verb form package inside <span class="extract"><span class="extract-syntax">R</span></span>. <span class="extract"><span class="extract-syntax">VERB_FORMS_HAP</span></span> has already been
declared with <a href="1-hl.html#SP18" class="internal">HierarchyLocations::att</a>, and has stem <span class="extract"><span class="extract-syntax">"form"</span></span> and type <span class="extract"><span class="extract-syntax">"_verb_form"</span></span>.
So the outcome might be a package called, say, <span class="extract"><span class="extract-syntax">form_16</span></span> of type <span class="extract"><span class="extract-syntax">_verb_form</span></span>
inside of <span class="extract"><span class="extract-syntax">R</span></span>; and then on the next call <span class="extract"><span class="extract-syntax">form_17</span></span>, and so on.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::attach_new_package</span><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">module_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">M</span><span class="plain-syntax">, </span><span class="reserved-syntax">package_request</span><span class="plain-syntax"> *</span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">hap_id</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">hierarchy_attachment_point</span><span class="plain-syntax"> *</span><span class="identifier-syntax">hap</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP18" class="function-link"><span class="function-syntax">HierarchyLocations::id_to_HAP</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">hap_id</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_submodule_package_of_this_identity</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">M</span><span class="plain-syntax">) </span><span class="identifier-syntax">R</span><span class="plain-syntax"> = </span><a href="1-ls.html#SP16" class="function-link"><span class="function-syntax">LargeScale::request_submodule_of</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">M</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                       </span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_submodule_package_of_this_identity</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">else</span><span class="plain-syntax">   </span><span class="identifier-syntax">R</span><span class="plain-syntax"> = </span><a href="1-ls.html#SP15" class="function-link"><span class="function-syntax">LargeScale::generic_submodule</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                       </span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_submodule_package_of_this_identity</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">this_exact_package</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">R</span><span class="plain-syntax"> = </span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">this_exact_package</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">this_exact_package_not_yet_created</span><span class="plain-syntax"> &gt;= </span><span class="constant-syntax">0</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        #</span><span class="identifier-syntax">ifdef</span><span class="plain-syntax"> </span><span class="identifier-syntax">CORE_MODULE</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">R</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Hierarchy::exotic_package</span><span class="plain-syntax">(</span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">this_exact_package_not_yet_created</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax">        #</span><span class="identifier-syntax">ifndef</span><span class="plain-syntax"> </span><span class="identifier-syntax">CORE_MODULE</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"exotic packages are not available in inter"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax">    } </span><span class="reserved-syntax">else</span><span class="plain-syntax"> </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_package_of_this_type</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="reserved-syntax">if</span><span class="plain-syntax"> ((</span><span class="identifier-syntax">R</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) ||</span>
<span class="plain-syntax">            (</span><span class="identifier-syntax">R</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">eventual_type</span><span class="plain-syntax"> != </span><a href="1-ls.html#SP19" class="function-link"><span class="function-syntax">LargeScale::package_type</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">,</span>
<span class="plain-syntax">                </span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">requirements</span><span class="plain-syntax">.</span><span class="element-syntax">any_package_of_this_type</span><span class="plain-syntax">)))</span>
<span class="plain-syntax">            </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"subpackage in wrong superpackage"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    }</span>

<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><a href="1-pck.html#SP2" class="function-link"><span class="function-syntax">Packaging::request</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">,</span>
<span class="plain-syntax">        </span><a href="1-pck.html#SP16" class="function-link"><span class="function-syntax">Packaging::make_iname_within</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">R</span><span class="plain-syntax">, </span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">name_stem</span><span class="plain-syntax">),</span>
<span class="plain-syntax">        </span><a href="1-ls.html#SP19" class="function-link"><span class="function-syntax">LargeScale::package_type</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">hap</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">type</span><span class="plain-syntax">));</span>
<span class="plain-syntax">}</span>
</pre>
<p class="commentary firstcommentary"><a id="SP20" class="paragraph-anchor"></a><b>&#167;20. Bookkeeping.</b>The following is a little clumsily defined to allow for the possibility that
this code is being compiled within a tool which defines no HLs or HAPs.
</p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">typedef</span><span class="plain-syntax"> </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">site_hierarchy_data</span><span class="plain-syntax"> {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="identifier-syntax">dictionary</span><span class="plain-syntax"> *</span><span class="identifier-syntax">HLs_indexed_by_name</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">ifndef</span><span class="plain-syntax"> </span><span class="identifier-syntax">NO_DEFINED_HL_VALUES</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">define</span><span class="plain-syntax"> </span><span class="identifier-syntax">NO_DEFINED_HL_VALUES</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">hierarchy_location</span><span class="plain-syntax"> *</span><span class="identifier-syntax">HLs_indexed_by_id</span><span class="plain-syntax">[</span><span class="identifier-syntax">NO_DEFINED_HL_VALUES</span><span class="plain-syntax">];</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">ifndef</span><span class="plain-syntax"> </span><span class="identifier-syntax">NO_DEFINED_HAP_VALUES</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">define</span><span class="plain-syntax"> </span><span class="identifier-syntax">NO_DEFINED_HAP_VALUES</span><span class="plain-syntax"> </span><span class="constant-syntax">1</span>
<span class="plain-syntax">    #</span><span class="identifier-syntax">endif</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">struct</span><span class="plain-syntax"> </span><span class="reserved-syntax">hierarchy_attachment_point</span><span class="plain-syntax"> *</span><span class="identifier-syntax">HAPs_indexed_by_id</span><span class="plain-syntax">[</span><span class="identifier-syntax">NO_DEFINED_HAP_VALUES</span><span class="plain-syntax">];</span>
<span class="plain-syntax">} </span><span class="reserved-syntax">site_hierarchy_data</span><span class="plain-syntax">;</span>

<span class="reserved-syntax">void</span><span class="plain-syntax"> </span><span class="function-syntax">HierarchyLocations::clear_site_data</span><button class="popup" onclick="togglePopup('usagePopup11')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup11">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::clear_site_data</span></span>:<br/>Building Module - <a href="1-bm.html#SP4">&#167;4</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">building_site</span><span class="plain-syntax"> *</span><span class="identifier-syntax">B</span><span class="plain-syntax"> = &amp;(</span><span class="identifier-syntax">I</span><span class="plain-syntax">-&gt;</span><span class="identifier-syntax">site</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">B</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HLs_indexed_by_name</span><span class="plain-syntax"> = </span><span class="identifier-syntax">Dictionaries::new</span><span class="plain-syntax">(512, </span><span class="identifier-syntax">FALSE</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">i</span><span class="plain-syntax">=0; </span><span class="identifier-syntax">i</span><span class="plain-syntax">&lt;</span><span class="identifier-syntax">NO_DEFINED_HL_VALUES</span><span class="plain-syntax">; </span><span class="identifier-syntax">i</span><span class="plain-syntax">++) </span><span class="identifier-syntax">B</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HLs_indexed_by_id</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">] = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">for</span><span class="plain-syntax"> (</span><span class="reserved-syntax">int</span><span class="plain-syntax"> </span><span class="identifier-syntax">i</span><span class="plain-syntax">=0; </span><span class="identifier-syntax">i</span><span class="plain-syntax">&lt;</span><span class="identifier-syntax">NO_DEFINED_HAP_VALUES</span><span class="plain-syntax">; </span><span class="identifier-syntax">i</span><span class="plain-syntax">++) </span><span class="identifier-syntax">B</span><span class="plain-syntax">-&gt;</span><span class="element-syntax">shdata</span><span class="plain-syntax">.</span><span class="element-syntax">HAPs_indexed_by_id</span><span class="plain-syntax">[</span><span class="identifier-syntax">i</span><span class="plain-syntax">] = </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<ul class="endnotetexts"><li>The structure site_hierarchy_data is private to this section.</li></ul>
<p class="commentary firstcommentary"><a id="SP21" class="paragraph-anchor"></a><b>&#167;21. Finding inames by name.</b></p>

<pre class="displayed-code all-displayed-code code-font">
<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::find_by_name</span><button class="popup" onclick="togglePopup('usagePopup12')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup12">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::find_by_name</span></span>:<br/>Identifier Finders - <a href="2-if.html#SP5_2">&#167;5.2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"empty extern"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">try</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP8" class="function-link"><span class="function-syntax">HierarchyLocations::name_to_iname</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">try</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><a href="1-hl.html#SP3" class="function-link"><span class="function-syntax">HierarchyLocations::con</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">name</span><span class="plain-syntax">, </span><a href="1-lr.html#SP6" class="function-link"><span class="function-syntax">LocationRequirements::plug</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">try</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP8" class="function-link"><span class="function-syntax">HierarchyLocations::name_to_iname</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">try</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>

<span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="function-syntax">HierarchyLocations::find_by_implied_name</span><button class="popup" onclick="togglePopup('usagePopup13')"><span class="comment-syntax">?</span><span class="popuptext" id="usagePopup13">Usage of <span class="code-font"><span class="function-syntax">HierarchyLocations::find_by_implied_name</span></span>:<br/>Identifier Finders - <a href="2-if.html#SP5_2">&#167;5.2</a></span></button><span class="plain-syntax">(</span><span class="identifier-syntax">inter_tree</span><span class="plain-syntax"> *</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">name</span><span class="plain-syntax">,</span>
<span class="plain-syntax">    </span><span class="identifier-syntax">text_stream</span><span class="plain-syntax"> *</span><span class="identifier-syntax">from_namespace</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">Str::len</span><span class="plain-syntax">(</span><span class="identifier-syntax">name</span><span class="plain-syntax">) == </span><span class="constant-syntax">0</span><span class="plain-syntax">) </span><span class="identifier-syntax">internal_error</span><span class="plain-syntax">(</span><span class="string-syntax">"empty extern"</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">inter_name</span><span class="plain-syntax"> *</span><span class="identifier-syntax">try</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP8" class="function-link"><span class="function-syntax">HierarchyLocations::name_to_iname</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">if</span><span class="plain-syntax"> (</span><span class="identifier-syntax">try</span><span class="plain-syntax"> == </span><span class="identifier-syntax">NULL</span><span class="plain-syntax">) {</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">TEMPORARY_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">)</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">WRITE_TO</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><span class="string-syntax">"implied`%S`%S"</span><span class="plain-syntax">, </span><span class="identifier-syntax">from_namespace</span><span class="plain-syntax">, </span><span class="identifier-syntax">name</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><a href="1-hl.html#SP3" class="function-link"><span class="function-syntax">HierarchyLocations::con</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, -1, </span><span class="identifier-syntax">N</span><span class="plain-syntax">, </span><a href="1-lr.html#SP6" class="function-link"><span class="function-syntax">LocationRequirements::plug</span></a><span class="plain-syntax">());</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">try</span><span class="plain-syntax"> = </span><a href="1-hl.html#SP8" class="function-link"><span class="function-syntax">HierarchyLocations::name_to_iname</span></a><span class="plain-syntax">(</span><span class="identifier-syntax">I</span><span class="plain-syntax">, </span><span class="identifier-syntax">N</span><span class="plain-syntax">);</span>
<span class="plain-syntax">        </span><span class="identifier-syntax">DISCARD_TEXT</span><span class="plain-syntax">(</span><span class="identifier-syntax">N</span><span class="plain-syntax">)</span>
<span class="plain-syntax">    }</span>
<span class="plain-syntax">    </span><span class="reserved-syntax">return</span><span class="plain-syntax"> </span><span class="identifier-syntax">try</span><span class="plain-syntax">;</span>
<span class="plain-syntax">}</span>
</pre>
<nav role="progress"><div class="progresscontainer">
    <ul class="progressbar"><li class="progressprev"><a href="1-org.html">&#10094;</a></li><li class="progresschapter"><a href="P-wtmd.html">P</a></li><li class="progresscurrentchapter">1</li><li class="progresssection"><a href="1-bm.html">bm</a></li><li class="progresssection"><a href="1-ls.html">ls</a></li><li class="progresssection"><a href="1-ip.html">ip</a></li><li class="progresssection"><a href="1-org.html">org</a></li><li class="progresscurrent">hl</li><li class="progresssection"><a href="1-lr.html">lr</a></li><li class="progresssection"><a href="1-trn.html">trn</a></li><li class="progresssection"><a href="1-pck.html">pck</a></li><li class="progresssection"><a href="1-in.html">in</a></li><li class="progresschapter"><a href="2-is.html">2</a></li><li class="progresschapter"><a href="3-prd.html">3</a></li><li class="progressnext"><a href="1-lr.html">&#10095;</a></li></ul></div>
</nav><!-- End of weave -->

		</main>
	</body>
</html>

